home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / clipper / ahelp5.zip / AHELP5.DOC < prev    next >
Text File  |  1990-11-04  |  21KB  |  488 lines
  1.  
  2.                            ***  IMPORTANT!!!  ***
  3.  
  4.  For a printed copy of this user guide, copy this file to your printer.
  5.  
  6.  If you have a previous version of AHELP, the three notes on this page may be
  7.  of interest to you.  Otherwise, proceed to the next page.
  8.  
  9.  
  10.  
  11.  Note 1:  AHELP5 requires a different file structure for the help file than
  12.    AHELP for Summer '87 (versions 1.x and 2.0) used.  The utility program named
  13.    AHELPUP.EXE converts the previous file structure to the new file structure.
  14.    Use it if you want to UPgrade any help files from AHELP version 1.x or 2.0
  15.    to AHELP5 files.  You do not need to use AHELPUP if you are upgrading from
  16.    AHELP version 2.1.
  17.  
  18.    To use AHELPUP, log into the directory where the old help file exists, and
  19.    enter
  20.  
  21.       AHELPUP [filename]
  22.  
  23.    where [filename] is the name of the old help file.  If you omit the file
  24.    name, AHELPUP will prompt for it.
  25.  
  26.  
  27.  
  28.  Note 2: AHELP5 names its index files differently from AHELP version 1.x or
  29.    2.0; the names of the two index files are derived from the name of the help
  30.    file.  This eliminates the inability of those previous versions of AHELP to
  31.    maintain more than one help file in a given subdirectory.
  32.  
  33.  
  34.  
  35.  Note 3: The parameters passed by Clipper 5.0 to AHELP5 are not consistent with
  36.    those passed by Summer '87 to AHELP.  Consequently, help files created with
  37.    AHELP are of little value to AHELP5.  The ASCII file import capability in
  38.    AHELP5 can partly overcome this Clipper inconsistency, if you use the
  39.    utility program HELPWRIT.EXE to write your old help files out in ASCII
  40.    format, then import them into AHELP5.
  41.  
  42.    To use HELPWRIT, enter
  43.  
  44.       HELPWRIT [filename]
  45.  
  46.    where [filename] is the name (no extension) of the help file.  If you omit
  47.    the file name, HELPWRIT will prompt for it.
  48.  
  49.  
  50.  
  51.         AHELP5.LIB - ADVANCED HELP SYSTEM FOR CLIPPER 5.0 APPLICATIONS
  52.  Version 1.0                                   Copyright (C) 1990, Capella Inc.
  53.  
  54.  
  55.  
  56.  Introduction
  57.  ------------
  58.  
  59.  Welcome to AHELP5!  This help system, for use with your Clipper 5.0 
  60.  applications, provides both context-sensitive and generalized help windows.
  61.  Features included with version 1 of AHELP5 (be sure to see version 2, p.7):
  62.  
  63.  * You control whether help windows have no border, a single-line border, or
  64.    a double-line border.
  65.  
  66.  * You control whether the cross-bars drawn inside the help windows have no
  67.    line, a single line, or a double line.
  68.  
  69.  * AHELP5 automatically determines the appropriate intersections.
  70.  
  71.  * You control what colors AHELP5 will use for the help window border, title,
  72.    content, and highlight bar in the help index window.
  73.  
  74.  * You control whether or not the end user has the ability to create or
  75.    modify help windows.
  76.  
  77.  * You control whether or not the help windows have drop shadows.
  78.  
  79.  * AHELP5 automatically positions the help window immediately below the screen
  80.    position of the input variable (e.g., a GET variable) if the window will fit
  81.    there; otherwise, the window appears immediately above the input variable.
  82.  
  83.  * AHELP5 provides a help index; whenever any help window is on the screen,
  84.    the user may press F1 to see the help index.  The help index is another
  85.    window with a scrolling alphabetic listing of help subjects.  The user
  86.    uses the cursor control keys to highlight the subject of interest, and
  87.    presses Enter to see the corresponding help window.  The user may also
  88.    type the first letter of the subject to move the highlight bar immediately
  89.    to the first occurrence of that letter.
  90.  
  91.  * AHELP5 is sensitive to the Clipper environment.  If the cursor is off when
  92.    help is invoked, it will be off when control returns to your application.
  93.    Conversely, if the cursor is on when help is invoked, it will be on when
  94.    control returns to your application.  The same principle applies to colors,
  95.    function keys, insert status, work area, and the status of SET CONSOLE,
  96.    DELETED, ESCAPE, and SCOREBOARD.
  97.  
  98.  * AHELP5 does not use any "wait state" commands (READ, WAIT, ACCEPT, INPUT,
  99.    MENU TO), to avoid conflicts with any pending GETs.  It uses the INKEY()
  100.    function for all keyboard input, with two exceptions: it calls DBEDIT() for
  101.    the help index window and MEMOEDIT() for displaying/editing help text.
  102.  
  103.  
  104.  
  105.  What do you have to do in order to use AHELP5?  Three things:
  106.  
  107.  1.  Insert a call to AHELP in your application with the setup parameters you
  108.      want to use as described in the next section.
  109.  
  110.  2.  Insert the command SET KEY XX TO AHELP in your application.
  111.  
  112.  3.  Compile your application and link, specifying AHELP5.LIB as one of the
  113.      LIB files (AHELP requires both CLIPPER.LIB and EXTEND.LIB).
  114.  
  115.  That's all.  The rest is transparent to your application.
  116.  
  117.  
  118.  Setup
  119.  -----
  120.  
  121.  The application must call AHELP with four parameters before starting the user
  122.  interface, in order to initialize the help system.  During initialization,
  123.  AHELP declares three PUBLIC memory variables:
  124.  
  125.     HELPOPTN   - an array of application options and file names
  126.     HELPCODE   - a character string for use by the application when no input
  127.                  variable is waiting -- AHELP uses the content of `HELPCODE' as
  128.                  its third parameter if the Clipper-passed third parameter is
  129.                  empty
  130.   and
  131.     HELPACTIVE - a logical variable set to true when AHELP is executing, and
  132.                  false otherwise.
  133.  
  134.  Also during initialization, AHELP5 checks for the existence of the help file
  135.  (and creates it if it is missing), and for the existence of the two index 
  136.  files needed (and creates them if they are missing).
  137.  
  138.  
  139.  Setup Syntax:
  140.  
  141.    AHELP( <expC1>, <expN>, <expC2>, <expA> )
  142.  
  143.  where
  144.  
  145.    <expC1> is the name of the application's Help File (one to eight characters)
  146.     
  147.    <expN>  is any value (ignored by AHELP5)
  148.  
  149.    <expC2> is a string of switch values: /Bn/Cn/Dn/En
  150.  
  151.         /Bn defines the help window Border: n=0 means no lines
  152.                                             n=1 means single line
  153.                                             n=2 means double line
  154.  
  155.         /Cn defines the window crossbar:    n=0 means no lines
  156.                                             n=1 means single line
  157.                                             n=2 means double line
  158.  
  159.         /Dn defines drop shadows:           n=0 means shadows are off
  160.                                             n=1 means shadows are on
  161.  
  162.  
  163.         /En defines Edit capability:        n=0 means edit is off
  164.                                             n=1 means edit is on
  165.  
  166.         These switches may appear in any order.  No other switches are defined
  167.         in version 1.  If any switch is missing, default values are:
  168.                 B = 2 (double line border)
  169.                 C = 1 (single line crossbar)
  170.                 D = 0 (drop shadows off)
  171.                 E = 1 (edit on)
  172.  
  173.    <expA>  is the name of a four-element character array containing 
  174.            screen color values:
  175.                 element 1 = the foreground/background colors of the help window
  176.                             content
  177.                 element 2 = the foreground/background colors of the help index
  178.                             highlight bar
  179.                 element 3 = the foreground/background colors of the help window
  180.                             title and bottom-row message
  181.                 element 4 = the foreground/background colors of the help window
  182.                             border
  183.  
  184.         This array is not needed after AHELP5 returns.
  185.  
  186.  Example 1:
  187.  
  188.    PRIVATE HCOLOR[4]
  189.    HCOLOR[1] = "N/W"    && content
  190.    HCOLOR[2] = "W+/B"   && highlight
  191.    HCOLOR[3] = "B/W"    && title
  192.    HCOLOR[4] = "W+/W"   && border
  193.    AHELP("MYAPHELP",0,"/B2/C1/D1/E0",HCOLOR)
  194.              |           |  |  |  |     |
  195.           filename       |  |  |  |   color
  196.                     double  |  |  |   array
  197.                     border  |  |  |   name
  198.                             |  |  |
  199.                        single  |  |
  200.                      crossbar  |  |
  201.